 /*******************************************************************************
  * Copyright (c) 2003, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ui.commands;

 import org.eclipse.swt.widgets.Shell;
 import org.eclipse.ui.IWorkbenchPartSite;
 import org.eclipse.ui.internal.util.Util;

 /**
  * </p>
  * An instance of this class represents a request to handle a command. A handler
  * submission specifies a list of conditions under which it would be appropriate
  * for a particular command to have a particular handler. These conditions
  * include things like the active part or the active shell. So, it is possible
  * to say things like: "when my part is active, please consider calling these
  * classes when you want to perform a cut, copy or paste".
  * </p>
  * <p>
  * The workbench considers all of the submissions it has received and choses the
  * ones it views as the best possible match.
  * </p>
  * <p>
  * This class is not intended to be extended by clients.
  * </p>
  * <p>
  * Note: this class has a natural ordering that is inconsistent with equals.
  * </p>
  *
  * @since 3.0
  * @see org.eclipse.ui.commands.IWorkbenchCommandSupport
  * @deprecated Please use <code>IHandlerService.activateHandler</code>
  * instead.
  * @see org.eclipse.ui.handlers.IHandlerService
  */
 public final class HandlerSubmission implements Comparable {

     /**
      * The part identifier for the part that should be active before this
      * submission can be considered. This value can be <code>null</code>, which
      * indicates that it should match any part.
      */
     private final String activePartId;

     /**
      * The shell that must be active before this submission can be considered.
      * This value can be <code>null</code>, which indicates that it should match
      * any shell.
      */
     private final Shell activeShell;

     /**
      * The workbench site that must be active before this submission can be
      * considered. This value can be <code>null</code>, which indicates that it
      * should match an workbench part site.
      */
     private final IWorkbenchPartSite activeWorkbenchPartSite;

     /**
      * The identifier for the command which the submitted handler handles. This
      * value cannot be <code>null</code>.
      */
     private final String commandId;

     /**
      * The handler being submitted. This value cannot be <code>null</code>.
      */
     private final IHandler handler;

     /**
      * The priority for this submission. In the event of all other factors
      * being equal, the priority will be considered in an attempt to resolve
      * conflicts. This value cannot be <code>null</code>.
      */
     private final Priority priority;

     /**
      * A lazily computed cache of the string representation of this submission.
      * This value is computed once; before it is computed, it is
      * <code>null</code>.
      */
     private transient String string;

     /**
      * Creates a new instance of this class.
      *
      * @param activePartId
      * the identifier of the part that must be active for this
      * request to be considered. May be <code>null</code>.
      * @param activeShell
      * the shell that must be active for this request to be
      * considered. May be <code>null</code>.
      * @param activeWorkbenchPartSite
      * the workbench part site of the part that must be active for
      * this request to be considered. May be <code>null</code>.
      * @param commandId
      * the identifier of the command to be handled. Must not be
      * <code>null</code>.
      * @param handler
      * the handler. Must not be <code>null</code>.
      * @param priority
      * the priority. Must not be <code>null</code>.
      */
     public HandlerSubmission(String activePartId, Shell activeShell,
             IWorkbenchPartSite activeWorkbenchPartSite, String commandId,
             IHandler handler, Priority priority) {
         if (commandId == null || handler == null || priority == null) {
             throw new NullPointerException ();
         }

         this.activePartId = activePartId;
         this.activeShell = activeShell;
         this.activeWorkbenchPartSite = activeWorkbenchPartSite;
         this.commandId = commandId;
         this.handler = handler;
         this.priority = priority;
     }

     /**
      * @see Comparable#compareTo(java.lang.Object)
      */
     public int compareTo(Object object) {
         HandlerSubmission castedObject = (HandlerSubmission) object;
         int compareTo = Util.compare(activeWorkbenchPartSite,
                 castedObject.activeWorkbenchPartSite);

         if (compareTo == 0) {
             compareTo = Util.compare(activePartId, castedObject.activePartId);

             if (compareTo == 0) {
                 compareTo = Util.compare(activeShell, castedObject.activeShell);

                 if (compareTo == 0) {
                     compareTo = Util.compare(priority, castedObject.priority);

                     if (compareTo == 0) {
                         compareTo = Util.compare(commandId,
                                 castedObject.commandId);

                         if (compareTo == 0) {
                             compareTo = Util.compare(handler,
                                     castedObject.handler);
                         }
                     }
                 }
             }
         }

         return compareTo;
     }

     /**
      * Returns the identifier of the part that must be active for this request
      * to be considered.
      *
      * @return the identifier of the part that must be active for this request
      * to be considered. May be <code>null</code>.
      */
     public String getActivePartId() {
         return activePartId;
     }

     /**
      * Returns the shell that must be active for this request to be considered.
      *
      * @return the shell that must be active for this request to be considered.
      * May be <code>null</code>.
      */
     public Shell getActiveShell() {
         return activeShell;
     }

     /**
      * Returns the workbench part site of the part that must be active for this
      * request to be considered.
      *
      * @return the workbench part site of the part that must be active for this
      * request to be considered. May be <code>null</code>.
      */
     public IWorkbenchPartSite getActiveWorkbenchPartSite() {
         return activeWorkbenchPartSite;
     }

     /**
      * Returns the identifier of the command to be handled.
      *
      * @return the identifier of the command to be handled. Guaranteed not to be
      * <code>null</code>.
      */
     public String getCommandId() {
         return commandId;
     }

     /**
      * Returns the handler.
      *
      * @return the handler. Guaranteed not to be <code>null</code>.
      */
     public IHandler getHandler() {
         return handler;
     }

     /**
      * Returns the priority.
      *
      * @return the priority. Guaranteed not to be <code>null</code>.
      */
     public Priority getPriority() {
         return priority;
     }

     /**
      * @see Object#toString()
      */
     public String toString() {
         if (string == null) {
             final StringBuffer stringBuffer = new StringBuffer ();
             stringBuffer.append("[activePartId="); //$NON-NLS-1$
 stringBuffer.append(activePartId);
             stringBuffer.append(",activeShell="); //$NON-NLS-1$
 stringBuffer.append(activeShell);
             stringBuffer.append(",activeWorkbenchSite="); //$NON-NLS-1$
 stringBuffer.append(activeWorkbenchPartSite);
             stringBuffer.append(",commandId="); //$NON-NLS-1$
 stringBuffer.append(commandId);
             stringBuffer.append(",handler="); //$NON-NLS-1$
 stringBuffer.append(handler);
             stringBuffer.append(",priority="); //$NON-NLS-1$
 stringBuffer.append(priority);
             stringBuffer.append(']');
             string = stringBuffer.toString();
         }

         return string;
     }
 }

